/**
 *  CloudEdit- Editor colaborativo peer-to-peer
 *  Author: Miguel Souto Bartolomé
 *  Web: http://code.google.com/p/cloudedit/
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package com.google.gwt.cloudedit.client;

import java.util.ArrayList;

import com.google.gwt.cloudedit.shared.DatosArchivo;
import com.google.gwt.cloudedit.shared.DatosListado;
import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * La interfaz LlamadaPastry se encarga de gestionar el lado cliente del servicio RCP 
 * asociado a una aplicación. La implementación de esta interfaz la realiza la clase
 * LlamadaPastryImpl presente en el lado servidor del servicio RCP.
 * 
 * @author Miguel Souto Bartolomé
 * @version 4.0 
 */
@RemoteServiceRelativePath("llamadaPastry")
public interface LlamadaPastry extends RemoteService {
	
	/**
	 * Inicia la red Pastry de tabla Hash distribuida asociada y levanta los
	 * servicios de gestión de archivos y gestión de mensajes correspondientes.
	 * Estas operaciones solo se realizan al conectarse la primera sesión cliente.
	 *
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public void inicia() throws IllegalArgumentException;
	
	/**
	 * Graba los cambios del archivo de datos que está siendo
	 * editado en la red distribuida.
	 *
	 * @param datos el archivo
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public void graba(DatosArchivo datos) throws IllegalArgumentException;
	
	/**
	 * Envia una notificación al resto de nodos suscritos al mismo grupo
	 * para que actualicen su informacion sobre el mismo si están editando
	 * el mismo archivo.
	 *
	 * @param xml notificación codificada en XML
	 * @param file el archivo que el emisor está editando
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public void notifica(String xml, DatosArchivo file) throws IllegalArgumentException;
	
	/**
	 * Comprueba si algún otro nodo ha modificado la información del archivo
	 * que se está editando.
	 *
	 * @return notificación codificada en XML
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public String comprueba() throws IllegalArgumentException;
	
	/**
	 * Genera un identificador de archivo único y graba un nuevo archivo
	 * de datos codificado en XML en la red Pastry.
	 *
	 * @param datos el nuevo archivo
	 * @param nombreAnterior the nombre anterior
	 * @return el nuevo archivo
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public DatosArchivo grabaComo(DatosArchivo datos, String nombreAnterior) throws IllegalArgumentException;
	
	/**
	 * Devuelve un archivo de la red Pastry.
	 *
	 * @param id el identificador único del archivo que se desea abrir
	 * @param nombreAnterior el nombre del archivo que se estaba editando
	 * @return el archivo que se desea abrir
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public DatosArchivo abre(String id, String nombreAnterior) throws IllegalArgumentException;
	
	/**
	 * Devuelve el listado de archivos presentes en la red Bunshin.
	 *
	 * @return el listado de archivos
	 */
	public ArrayList<DatosListado> listado();
	
	/**
	 * Comprueba si un nombre de archivo ya existe en la red Bunshin.
	 *
	 * @param text el nombre de archivo
	 * @return "EXISTE" si el archivo ya existe, el parámetro de entrada text en otro caso
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public String comprobarNombre(String text) throws IllegalArgumentException;

	/**
	 * Graba el archivo en caso de no ser nuevo y cierra la conexión.
	 *
	 * @param datos nombre del archivo que se está editando
	 * @param modoEdicion el modo de edición
	 * @throws IllegalArgumentException the illegal argument exception
	 */
	public void cerrar(DatosArchivo datos, String modoEdicion) throws IllegalArgumentException;

	/**
	 * Comparar el contenido nuevo del fichero abierto con el antiguo almacenado
	 * por el editor, y nos devuelve el contenido nuevo con los cambios marcados.
	 *
	 * @param textoAntiguo el texto antiguo
	 * @param textoNuevo el texto nuevo
	 * @return el texto marcado
	 */
	public String comparar(String textoAntiguo, String textoNuevo);
	
	/**
	 * Método de apoyo a los casos de prueba para adecuar el contexto del Servlet y
	 * cerrar el nodo.
	 *
	 * @param operacion la operación
	 */
	public void resetContexto(String operacion);

}